package com.tbynet.jwp.service;

import com.tbynet.jwp.service.dto.request.TermRequest;
import com.tbynet.jwp.service.dto.response.TermResponse;

import java.math.BigInteger;
import java.util.List;

/**
 * 分类项管理器接口
 * 服务编排层，负责组合多个Service方法完成复杂业务用例，并管理事务
 * 对标WordPress 4.9分类项管理功能
 *
 * @author 佰亿互联
 * @version 2.0
 * @since 2025-11-04
 */
public interface TermService {

    // ========== 核心分类项管理方法 ==========

    /**
     * 创建分类项
     * 对应WordPress：wp_insert_term函数
     * 服务编排：验证分类项是否存在 -> 创建分类项 -> 设置分类项元数据（如果有）
     *
     * @param request 创建分类项请求
     * @return 创建的分类项详细信息
     * @throws IllegalArgumentException 当参数验证失败时抛出
     */
    TermResponse.DetailInfo createTerm(TermRequest request);

    /**
     * 更新分类项
     * 对应WordPress：wp_update_term函数
     * 服务编排：获取现有分类项 -> 更新分类项 -> 更新分类项元数据（如果有）
     *
     * @param request 更新分类项请求
     * @return 更新后的分类项详细信息
     * @throws IllegalArgumentException 当参数验证失败时抛出
     */
    TermResponse.DetailInfo updateTerm(TermRequest request);

    /**
     * 删除分类项
     * 对应WordPress：wp_delete_term函数
     * 服务编排：检查分类项是否被使用 -> 删除分类项元数据 -> 删除分类项
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否删除成功
     * @throws IllegalStateException 当分类项有关联文章或子分类项时抛出
     */
    Boolean deleteTerm(BigInteger termId, String taxonomy);

    /**
     * 批量删除分类项
     * 对应WordPress：wp_delete_term函数（批量操作）
     * 服务编排：循环处理每个分类项 -> 执行删除操作 -> 返回成功数量
     *
     * @param request 批量删除请求
     * @return 批量删除结果
     */
    TermResponse.BatchOperationResult batchDeleteTerms(TermRequest request);

    /**
     * 获取分类项详情
     * 对应WordPress：get_term函数
     * 服务编排：获取分类项基础信息 -> 获取分类项元数据 -> 组合响应
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项详细信息
     */
    TermResponse.DetailInfo getTermDetail(BigInteger termId, String taxonomy);

    /**
     * 获取分类项列表
     * 对应WordPress：get_terms函数
     * 服务编排：查询分类项列表 -> 获取每个分类项的元数据（如果需要） -> 组合响应
     *
     * @param request 查询请求
     * @return 分类项列表响应
     */
    TermResponse.ListResult listTerms(TermRequest request);

    // ========== WordPress 4.9 层级和关系方法 ==========

    /**
     * 获取分类项层级结构
     * 对应WordPress：get_terms函数（带层级参数）
     * 服务编排：获取顶级分类项 -> 递归获取子分类项 -> 构建层级结构
     *
     * @param taxonomy 分类法类型
     * @param parentId 父级分类项ID（可选，null表示获取顶级分类项）
     * @return 层级结构响应
     */
    TermResponse.HierarchyResult getTermHierarchy(String taxonomy, BigInteger parentId);

    /**
     * 根据文章获取分类项
     * 对应WordPress：wp_get_post_terms函数
     * 服务编排：根据文章ID获取分类项列表 -> 获取每个分类项的详细信息 -> 组合响应
     *
     * @param postId 文章ID
     * @param taxonomy 分类法类型
     * @return 分类项列表响应
     */
    TermResponse.ListResult getTermsByPostId(BigInteger postId, String taxonomy);

    // ========== WordPress 4.9 统计和元数据方法 ==========

    /**
     * 获取分类项统计信息
     * 对应WordPress自定义功能
     * 服务编排：获取各分类法的分类项数量 -> 获取最近创建的分类项 -> 获取最常用的分类项
     *
     * @return 统计信息响应
     */
    TermResponse.Statistics getTermStatistics();

    /**
     * 设置分类项元数据
     * 对应WordPress：update_term_meta函数
     * 服务编排：检查分类项是否存在 -> 设置元数据
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return 是否设置成功
     */
    Boolean setTermMeta(BigInteger termId, String metaKey, Object metaValue);

    /**
     * 获取分类项元数据
     * 对应WordPress：get_term_meta函数
     * 服务编排：检查分类项是否存在 -> 获取元数据
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键（可选，null表示获取所有元数据）
     * @return 元数据值
     */
    Object getTermMeta(BigInteger termId, String metaKey);

    // ========== WordPress 4.9 高级功能方法 ==========

    /**
     * 更新分类项计数
     * 对应WordPress：wp_update_term_count函数
     * 服务编排：获取分类项关联的文章数量 -> 更新分类项计数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否更新成功
     */
    Boolean updateTermCount(BigInteger termId, String taxonomy);

    /**
     * 清理空分类项
     * 对应WordPress：wp_delete_unused_terms函数
     * 服务编排：查找空分类项 -> 批量删除空分类项
     *
     * @param taxonomy 分类法类型
     * @return 清理结果响应
     */
    TermResponse.BatchOperationResult cleanupUnusedTerms(String taxonomy);

    /**
     * 搜索分类项
     * 对应WordPress：get_terms函数（带搜索参数）
     * 服务编排：执行搜索 -> 获取分类项详情 -> 组合响应
     *
     * @param keyword 搜索关键词
     * @param taxonomy 分类法类型（可选）
     * @param limit 返回数量（可选，默认20）
     * @return 搜索结果响应
     */
    TermResponse.ListResult searchTerms(String keyword, String taxonomy, Integer limit);

    /**
     * 合并分类项
     * 对应WordPress：wp_merge_terms函数
     * 服务编排：验证分类项存在 -> 转移关联关系 -> 更新文章分类 -> 删除源分类项
     *
     * @param sourceTermId 源分类项ID
     * @param targetTermId 目标分类项ID
     * @param taxonomy 分类法类型
     * @return 合并结果响应
     */
    TermResponse.MergeResult mergeTerms(BigInteger sourceTermId, BigInteger targetTermId, String taxonomy);

    // ========== WordPress 4.9 默认分类项管理 ==========

    /**
     * 设置默认分类项
     * 对应WordPress：set_default_category函数
     * 服务编排：验证分类项存在 -> 更新系统设置 -> 清理缓存
     *
     * @param taxonomy 分类法类型
     * @param termId 默认分类项ID
     * @return 设置结果响应
     */
    TermResponse.OperationResult setDefaultTerm(String taxonomy, BigInteger termId);

    /**
     * 获取默认分类项
     * 对应WordPress：get_default_category函数
     * 服务编排：获取系统设置 -> 获取分类项详情
     *
     * @param taxonomy 分类法类型
     * @return 默认分类项详情
     */
    TermResponse.DetailInfo getDefaultTerm(String taxonomy);

    // ========== WordPress 4.9 转换和复制方法 ==========

    /**
     * 转换分类项分类法
     * 对应WordPress：wp_transform_term函数
     * 服务编排：验证分类项 -> 创建新分类项 -> 转移关联 -> 更新元数据
     *
     * @param termId 分类项ID
     * @param sourceTaxonomy 源分类法
     * @param targetTaxonomy 目标分类法
     * @return 转换结果响应
     */
    TermResponse.TransformResult transformTerm(BigInteger termId, String sourceTaxonomy, String targetTaxonomy);

    /**
     * 复制分类项
     * 对应WordPress自定义功能
     * 服务编排：获取源分类项 -> 创建新分类项 -> 复制元数据
     *
     * @param termId 源分类项ID
     * @param newName 新分类项名称
     * @param taxonomy 分类法类型
     * @return 复制结果响应
     */
    TermResponse.DetailInfo duplicateTerm(BigInteger termId, String newName, String taxonomy);

    // ========== WordPress 4.9 分类法管理方法 ==========

    /**
     * 获取分类法详情
     * 对应WordPress：get_taxonomy函数
     * 服务编排：获取分类法信息 -> 获取分类项统计 -> 组合响应
     *
     * @param taxonomy 分类法类型
     * @return 分类法详情响应
     */
    TermResponse.TaxonomyInfo getTaxonomyDetail(String taxonomy);

    /**
     * 获取分类项路径
     * 对应WordPress：get_term_parents_list函数
     * 服务编排：获取分类项 -> 递归获取父级 -> 构建路径
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项路径响应
     */
    TermResponse.PathResult getTermPath(BigInteger termId, String taxonomy);

    /**
     * 检查分类项关系
     * 服务编排：检查祖先关系 -> 检查同层级 -> 返回关系信息
     *
     * @param termId1 分类项1 ID
     * @param termId2 分类项2 ID
     * @param taxonomy 分类法类型
     * @return 关系检查响应
     */
    TermResponse.RelationCheckResult checkTermRelation(BigInteger termId1, BigInteger termId2, String taxonomy);

    // ========== WordPress 4.9 批量操作方法 ==========

    /**
     * 批量更新分类项
     * 服务编排：验证分类项 -> 批量更新父级 -> 更新计数
     *
     * @param request 批量更新请求
     * @return 批量操作结果
     */
    TermResponse.BatchOperationResult batchUpdateTerms(TermRequest request);

    /**
     * 重新生成分类项别名
     * 对应WordPress：wp_unique_term_slug函数
     * 服务编排：获取分类项 -> 生成新别名 -> 验证唯一性 -> 更新
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 别名更新结果
     */
    TermResponse.SlugUpdateResult regenerateTermSlug(BigInteger termId, String taxonomy);

    // ========== WordPress 4.9 分析和推荐方法 ==========

    /**
     * 获取分类项使用分析
     * 对应WordPress自定义功能
     * 服务编排：获取使用统计 -> 分析趋势 -> 组合响应
     *
     * @param taxonomy 分类法类型
     * @param days 分析天数（可选，默认30天）
     * @return 使用分析响应
     */
    TermResponse.UsageAnalysisResult getTermUsageAnalysis(String taxonomy, Integer days);

    /**
     * 清理分类项缓存
     * 对应WordPress：clean_term_cache函数
     * 服务编排：清理本地缓存 -> 清理分布式缓存 -> 返回结果
     *
     * @param termIds 分类项ID列表
     * @param taxonomy 分类法类型
     * @return 缓存清理结果
     */
    TermResponse.CacheCleanResult cleanTermCache(List<BigInteger> termIds, String taxonomy);

    /**
     * 验证分类项数据完整性
     * 服务编排：检查孤儿分类项 -> 检查计数一致性 -> 返回验证结果
     *
     * @param taxonomy 分类法类型
     * @return 数据完整性验证结果
     */
    TermResponse.IntegrityCheckResult validateTermIntegrity(String taxonomy);

    /**
     * 获取分类项推荐
     * 对应WordPress：get_terms函数（按count排序）
     * 服务编排：分析使用模式 -> 基于内容推荐 -> 返回推荐结果
     *
     * @param postId 文章ID（可选）
     * @param taxonomy 分类法类型
     * @param limit 推荐数量（可选，默认5）
     * @return 分类项推荐响应
     */
    TermResponse.RecommendationResult getTermRecommendations(BigInteger postId, String taxonomy, Integer limit);
}